<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<!-- HTML file produced from file: manual.tex --
 -- using Hyperlatex v 2.3.1 (c) Otfried Cheong--
 -- on Emacs 21.4 (patch 15) "Security Through Obscurity" XEmacs Lucid, Fri Dec  3 20:36:27 2004 -->
<HEAD>
<TITLE>Scheme 48 Manual -- Accessing Scheme data from C</TITLE>

</HEAD><BODY BGCOLOR="#ffffff">
<EM>Scheme 48 Manual</EM> | <A HREF="s48manual.html#top_node">Contents</A> | In Chapter: <A HREF="s48manual_65.html">Mixing Scheme 48 and C</A><BR>Previous: <A HREF="s48manual_72.html">Accessing Scheme data from C</A> | Next: <A HREF="s48manual_72.html">Accessing Scheme data from C</A>
<H2>Accessing Scheme data from C</H2>

<P>The C header file <CODE>scheme48.h</CODE> provides
 access to Scheme&nbsp;48 data structures.
The type <CODE>s48_value</CODE> is used for Scheme values.
When the type of a value is known, such as the integer returned
 by <CODE>vector-length</CODE> or the boolean returned by <CODE>pair?</CODE>,
 the corresponding C procedure returns a C value of the appropriate
 type, and not a <CODE>s48_value</CODE>.
Predicates return <CODE>1</CODE> for true and <CODE>0</CODE> for false.
<P><H3><A NAME="1">Constants</A></H3>

<P>The following macros denote Scheme constants:
<UL><LI><CODE>S48_FALSE</CODE> is <CODE>#f</CODE>.
<LI><CODE>S48_TRUE</CODE> is <CODE>#t</CODE>.
<LI><CODE>S48_NULL</CODE> is the empty list.
<LI><CODE>S48_UNSPECIFIC</CODE> is a value used for functions which have no
  meaningful return value
 (in Scheme&nbsp;48 this value returned by the nullary procedure <CODE>unspecific</CODE>
 in the structure <CODE>util</CODE>).
<LI><CODE>S48_EOF</CODE> is the end-of-file object
 (in Scheme&nbsp;48 this value is returned by the nullary procedure <CODE>eof-object</CODE>
 in the structure <CODE>i/o-internal</CODE>).
</UL>
<P><H3><A NAME="2">Converting values</A></H3>
<P>The following macros and functions convert values between Scheme and C
 representations.
The `extract' ones convert from Scheme to C and the `enter's go the other
 way.
<P><UL><LI><CODE>int       S48_EXTRACT_BOOLEAN(s48_value)</CODE>
<LI><CODE>unsigned char s48_extract_char(s48_value)</CODE>
<LI><CODE>char *    s48_extract_string(s48_value)</CODE>
<LI><CODE>char *    s48_extract_byte_vector(s48_value)</CODE>
<LI><CODE>long      s48_extract_integer(s48_value)</CODE>
<LI><CODE>double    s48_extract_double(s48_value)</CODE>
<LI><CODE>s48_value S48_ENTER_BOOLEAN(int)</CODE>
<LI><CODE>s48_value s48_enter_char(unsigned char)</CODE>
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_enter_string(char *)</CODE></td> <td align=right>(may GC)</td></tr></table>
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_enter_byte_vector(char *, long)</CODE></td> <td align=right>(may GC)</td></tr></table>
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_enter_integer(long)</CODE></td> <td align=right>(may GC)</td></tr></table>
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_enter_double(double)</CODE></td> <td align=right>(may GC)</td></tr></table>
</UL>
<P><CODE>S48_EXTRACT_BOOLEAN</CODE> is false if its argument is
 <CODE>#f</CODE> and true otherwise.
 <CODE>S48_ENTER_BOOLEAN</CODE> is <CODE>#f</CODE> if its argument is zero
  and <CODE>#t</CODE> otherwise.
<P> <CODE>s48_extract_string</CODE> and <CODE>s48_extract_byte_vector</CODE> return
 pointers to the actual
 storage used by the string or byte vector.
 These pointers are valid only until the next
 <A HREF="s48manual_74.html">garbage collection</A>.
<P>The second argument to <CODE>s48_enter_byte_vector</CODE> is the length of
 byte vector.
<P><CODE>s48_enter_integer()</CODE> needs to allocate storage when
 its argument is too large to fit in a Scheme&nbsp;48 fixnum.
In cases where the number is known to fit within a fixnum (currently 30 bits
 including the sign), the following procedures can be used.
These have the disadvantage of only having a limited range, but
 the advantage of never causing a garbage collection.
<CODE>S48_FIXNUM_P</CODE> is a macro that true if its argument is a fixnum
 and false otherwise.
<P><UL><LI><CODE>int       S48_TRUE_P(s48_value)</CODE>
<LI><CODE>int       S48_FALSE_P(s48_value)</CODE>
</UL>
<P><CODE>S48_TRUE_P</CODE> is true if its argument is <CODE>S48_TRUE</CODE>
 and <CODE>S48_FALSE_P</CODE> is true if its argument is <CODE>S48_FALSE</CODE>.
<P><UL><LI><CODE>int       S48_FIXNUM_P(s48_value)</CODE>
<LI><CODE>long      s48_extract_fixnum(s48_value)</CODE>
<LI><CODE>s48_value s48_enter_fixnum(long)</CODE>
<LI><CODE>long      S48_MAX_FIXNUM_VALUE</CODE>
<LI><CODE>long      S48_MIN_FIXNUM_VALUE</CODE>
</UL>
<P>An error is signalled if <CODE>s48_extract_fixnum</CODE>'s argument
 is not a fixnum or if the argument to <CODE>s48_enter_fixnum</CODE> is less than
 <CODE>S48_MIN_FIXNUM_VALUE</CODE> or greater than <CODE>S48_MAX_FIXNUM_VALUE</CODE>
 (<I>-2<sup>29</sup></I> and <I>2<sup>29</sup>-1</I> in the current system).
<P><H3><A NAME="3">C versions of Scheme procedures</A></H3>
<P>The following macros and procedures are C versions of Scheme procedures.
The names were derived by replacing `<CODE>-</CODE>' with `<CODE>_</CODE>',
 `<CODE>?</CODE>' with `<CODE>_P</CODE>', and dropping `<CODE>!</CODE>.
<P><UL><LI><CODE>int       S48_EQ_P(s48_value, s48_VALUE)</CODE>
<LI><CODE>int       S48_CHAR_P(s48_value)</CODE>
</UL>
<UL><LI><CODE>int       S48_PAIR_P(s48_value)</CODE>
<LI><CODE>s48_value S48_CAR(s48_value)</CODE>
<LI><CODE>s48_value S48_CDR(s48_value)</CODE>
<LI><CODE>void      S48_SET_CAR(s48_value, s48_value)</CODE>
<LI><CODE>void      S48_SET_CDR(s48_value, s48_value)</CODE>
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_cons(s48_value, s48_value)</CODE></td> <td align=right>(may GC)</td></tr></table>
<LI><CODE>long      s48_length(s48_value)</CODE> 
</UL>
<UL><LI><CODE>int       S48_VECTOR_P(s48_value)</CODE> 
<LI><CODE>long      S48_VECTOR_LENGTH(s48_value)</CODE> 
<LI><CODE>s48_value S48_VECTOR_REF(s48_value, long)</CODE> 
<LI><CODE>void      S48_VECTOR_SET(s48_value, long, s48_value)</CODE> 
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_make_vector(long, s48_value)</CODE></td> <td align=right>(may GC)</td></tr></table>
</UL>
<UL><LI><CODE>int       S48_STRING_P(s48_value)</CODE> 
<LI><CODE>long      S48_STRING_LENGTH(s48_value)</CODE> 
<LI><CODE>char      S48_STRING_REF(s48_value, long)</CODE> 
<LI><CODE>void      S48_STRING_SET(s48_value, long, char)</CODE> 
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_make_string(long, char)</CODE></td> <td align=right>(may GC)</td></tr></table>
</UL>
<UL><LI><CODE>int       S48_SYMBOL_P(s48_value)</CODE> 
<LI><CODE>s48_value s48_SYMBOL_TO_STRING(s48_value)</CODE> 
</UL>
<UL><LI><CODE>int       S48_BYTE_VECTOR_P(s48_value)</CODE> 
<LI><CODE>long      S48_BYTE_VECTOR_LENGTH(s48_value)</CODE> 
<LI><CODE>char      S48_BYTE_VECTOR_REF(s48_value, long)</CODE> 
<LI><CODE>void      S48_BYTE_VECTOR_SET(s48_value, long, int)</CODE> 
<LI><table border=0 cellspacing=0 cellpadding=0 width=80%>
<tr> <td><CODE>s48_value s48_make_byte_vector(long, int)</CODE></td> <td align=right>(may GC)</td></tr></table>
</UL>
<P><P>
  
Previous: <A HREF="s48manual_72.html">Accessing Scheme data from C</A> | Next: <A HREF="s48manual_72.html">Accessing Scheme data from C</A></BODY></HTML>
